home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Developer CD v1.1
/
Amiga Developer CD v1.1 - May 1996 (1996)(Schatztruhe)[!].iso
/
Contributions
/
IAM
/
Networking
/
Envoy-2.0
/
obs
/
Project_Overview
< prev
next >
Wrap
Text File
|
1994-12-22
|
26KB
|
600 lines
Envoy
DO NOT REDISTRIBUTE
Developer's Overview
8/21/92
Amiga Networking Group
Developer's Overview
This document is a collection of select pages from the Commodore internal
product description for Envoy. It is provided as a background text for
development to Envoy, as well as an indication of the directions Commodore
intends to take with Envoy. This text is included only as a courtesy to
developers. Any and all details within are subject to change.
Summary
Features
The Envoy software package will enable all Amiga computers (including the
A500 and A600) to transparently share filesystems and printers with each other.
It will support third-party networking applications. Easy configuration for
simple networks, and operation in complex network environments will both be
part of the initial package. Security features will unobtrusively discourage
unauthorized use of network resources. The Amiga GUI will be used extensively
to make the package easy to configure and to use.
Hardware Requirements
Envoy makes use of the SANA-II Network Device Driver Specification, allowing
the package to be used with any networking hardware that has a compliant
device driver. Envoy can be used on any 512k Amiga running 2.0 or better.
Availability & Distribution
Information on the future availability of Envoy, including plans for
distribution is not available at this time.
The diagram below gives an overview of the Envoy project architecture.
The sections which follow provide some additional details.
+----------------+ +-----------------+ +--------------+
| | | | | |
| Applications | | Printer Svcs. | | Network FS |
| | | | | |
+----------------+ +-----------------+ +--------------+
| | | | | |
| | | +------+ | |
| | | | | |
| +---------------------------------------+ | |
| | | | |
| | Services Manager & services.library | | |
| | | | |
| +---------------------------------------+ | |
| | | | |
| | | | |
| | | | |
| | +-----------------+ |
| | | | |
| | | User Accounts | |
| | | | |
| | +-----------------+ |
| | | |
| | | |
| | | |
+--------------------------------------------------------------+
| |
| nipc.library |
| |
+--------------------------------------------------------------+
|
|
|
+--------------------+
| |
| SANA-II Drivers |
| |
+--------------------+
nipc.library Architecture
The nipc.library is the communications workhorse and largest piece of Envoy.
It provides a Transaction-based reliable communications path between multiple
Amigas, above any compliant SANA II device. To understand exactly where the
nipc.library fits into the broad APPN picture, one needs to have a general
understanding of the different layers that define the nipc.library and it's
interactions with others. As a reference, please note figure A.
As figure A shows, the
nipc.library sits directly
+--------------+ +------------+ above the device drivers
| Envoy | | Stand | for each piece of
| Applications | | Alone Apps.| networking hardware in
+--------------+ +------------+ use, and directly below
NIPC API-----> \ / either applications or
+------------------------------+ another library. Some
| nipc.library | applications may only
+------------------------------+ require the ability to
S-II Std Interface--> | transmit and receive data
+------------------------------+ reliably - and not require
| SANA-II Device Drivers | some of the more complex
+------------------------------+ features that higher levels
| of Envoy provide. Thus,
+------------------------------+ these programs
| Networking Hardware | communicate directly
+------------------------------+ with the nipc.library.
Figure A.
Figure B. provides a more
detailed diagram of exactly what levels make up the nipc.library, as well as
the interfaces between levels.
The lowest level is the specific networking hardware. This could be anything
from an A2065 ethernet board to a low-speed serial link. The only requirement
on the hardware is that a SANA II device driver must exist for it. The hardware
communicates with the next layer up (the SANA II device drivers) through an
arbitrary hardware specific interface. This is dependant on the exact hardware
used, and may vary from implementation to implementation (for example, two
differently designed ethernet boards will communicate with their
device drivers differently - as they +----------------------------+
may have been designed around | 5 Applications |
different chipsets). +----------------------------+
/ |
| +----------------------------+
The second level consists of one or | | 4 NIPC "Presentation" |
more SANA II device drivers. Please | +----------------------------+
reference the document "SANA-II Network N | |
Device Specification", 5/5/92 for I \ +----------------------------+
more specific information. The SANA II P < | 3 RDP & UDP |
device drivers provide a standard C / +----------------------------+
interface between wildly different | |
networking software and networking | +----------------------------+
hardware. | | 2 IP, ICMP, ARP |
| +----------------------------+
\ |
The third leve marks the beginning +----------------------------+
of a set of two levels of the proposed | 1 SANA-II Driver |
design which are intentionally insulated +----------------------------+
from the rest of the design. (These can |
be seen in figure B, as levels 3 and 4, +----------------------------+
as well as the interfaces between 3, 4, and | 0 Networking Hardware |
5.) The goal in doing this is to prevent the +----------------------------+
nipc.library from being necessarily tied
to a specific networking protocol. Figure B.
For instance, it's entirely
possible to create an nipc.library which is based on Novell NetWare instead of
the protocol stack shown in figure A. Level two in figure B is similar to the
ISO 'Network' layer in most functions. It's function is to packetize and route
data from one site to another. This level is made up of implementations of the
internet protocol (IP), the internet control message protocol (ICMP), and the
address resolution protocol (ARP).
Above the Internet Protocol is the Reliable Datagram Protocol - which makes up
level three. RDP provides reliability and sequencing, among other features, to
the datagram service.
Level four contains the NIPC Presentation layer. Specifically, this level
provides the services specified in the nipc.library Autodocs, based on the
services provided to it by lower levels (RDP and level four, in this instance).
Communication to the next higher level is provided through the interface
defined in the previously mentioned standard.
While a layered model is an excellent method by which one may understand
networking protocols, it's a decidedly poor way to implement a protocol stack.
In light of this, levels two, three, and four are not entirely distinct.
Communication between these levels is done with a buffering scheme that's
designed to minimize data copying.
The library itself contains everything from the SANA II interface up
through the NIPC API (this is shown bracketed on figure B).
nipc.library Overview
Definition
The nipc.library provides reliable, transaction-oriented networking abilities
to an Amiga, with a familiar API.
Concepts
To fully understand the library, a knowledge of a few essential NIPC concepts
is required:
Entity: A communications endpoint. A single Entity can be part of a number of
different communications paths - meaning that one Entity may be communicating
with many other Entities at the same time. While it's useful for the purposes
of descriptions to illustrate a pair of Entities communicating, it's important
to understand that this isn't a limitation. An Entity is identified by both
it's name, and the name of the machine on which it exists.
Communications Path: An imaginary line drawn between two Entities defining a
line of data transfer.
Transaction: The process used to transfer data in NIPC. A Transaction is made
up of two distinct phases - the time in which a Transaction is a request and
the time in which it is a response. A Transaction always takes place on a
communications path between two Entities. See Figure A. as a reference.
Request
+-------------+ -------------------> +-------------+
| | | |
| Entity A | | Entity B |
| | | |
+-------------+ <------------------- +-------------+
(source) Response (dest)
Figure A.
The flow of a Transaction between Entities.
Request: The first phase of a Transaction, where a source Entity (Entity A,
above) sends a request packet to a destination Entity (Entity B, above). A
Request can be identified by a single-byte command and a variable length data
section.
Response: The second phase of a Transaction, where a destination Entity
processes a request packet, provides an Error code, and (if required) provides
a variable length data section.
Operation
The nipc.library provides operations for communicating between Entities,
regardless of whether the communications path involves transferring data
from one machine to another, or merely transferring data between two Entities
on a single machine. The operations as seen by the application program are
identical, though the library obviously processes the data in different ways.
Figure B. shows the modelling of how a Transaction appears when operated
through a networked device.
Network
\ \
+-------------+ ------->/ /--------> +-------------+
| | \ \ | |
| Entity A | / / | Entity B |
| | \ \ | |
+-------------+ <-------/ /<-------- +-------------+
\ \
Figure B.
A Transaction's conceptual
flow over a network.
When refer encing the diagram above, keep in mind that this is only a
model -- the transfer of data only appears to work in this way. Knowledge
of this model is all that is necessary for using the library. While this
model is straightfoward and simple enough to expect developers to understand
thoroughly, it's too simplistic to use for the actual library
implementation - which presents a more complex situation. However, the
model serves an important role by insulating the developer from the
complexities of networking. In our implementation, for each communications
path in use there exists something called a Link Entity. It is between
these Link Entities that networked communications actually occur. Each
Entity may have several Link Entities -- one for the local side of each
communications path. This scheme is shown in Figure C. This scheme lends
itself quite well to NIPC. Each Link Entity might be considered a local
extension of the Entity on the other side of the communications path.
For instance, the leftmost Link (shorthand for "Link Entity") in Figure C.
might be considered the local extension of Entity B. Thus, for library
function calls, when a program attempts to reference a remote Entity (one
on another machine), it actually references the Link that symbolizes the
remote Entity. The networking portion of nipc.library fills in the rest.
Network
+----+\ \+----+
+-------------+ ->| |/ /| |--> +-------------+
| | | |\ \| | | |
| Entity A | |LINK|/ /|LINK| | Entity B |
| | | |\ \| | | |
+-------------+ <-| |/ /| |<-- +-------------+
+----+\ \+----+
Figure C.
A Transaction's actual
flow over a network.
For a local transaction (where the source and destination Entities are on
the same machine), there's very little overhead; the Transaction structure
is simply passed to the destination Entity.
Envoy Services
Introduction
One of the problems when writing client-server applications is determining
exactly how the client is supposed to initiate a connection with a server.
Another problem is deciding how and when the server's process is to be
started. It would seem desirable to have a system that provided a
standard way to handle both problems. This is where the Envoy Services
system comes into play.
The Envoy Services system is designed to standardize the way in which nipc
client applications initiate connections with nipc servers. This is done
by providing a services.library that deals with locating the requested service
on the remote machine and making the connection to the server.
The other problem, that of how and when to start servers, is handled on
the "server side" of the connection via the Envoy Services Manager. The
Envoy Services Manager receives requests for services from the client machine
and then passes this information on to an Envoy Service which then takes
any actions that are required to activate the server.
The Envoy Services themselves are implemented as Amiga shared libraries.
By using this model, Services may be dynamically loaded from disk, and may
also be flushed if they are inactive. Services also make use of special
library LVO's that are used to start services, query the service, etc.
Connection to a Service
The first step in connecting to a service is to open nipc.library and the
services.library. You must use nipc.library to create the Entity that
you will be using for your side of the communications path. Then, you call
the services.library function FindService() which will make an attempt to
connect to the service you are requesting to use.
Example:
...
if(svc_entity = FindService("Cruncher","Printer Service",my_entity,
FSVC_UserName,"Joe",
FSVC_Password,"Joe's Password",
FSVC_Error, &error_code,
TAG_DONE)
{
...
FindService() requires that you specify the name of the host that the
service you want to use is located on (in the above case, "Cruncher") ,
the name of the service ("Printer Service"), and the Entity that you
will use for your side of the connection. You may also optionally
specify a user's name, a user's password or a pointer to a ULONG that
will be filled in with an error code (if any) if the connection failed.
For more information, please see the services.library/FindServce()
autodoc.
Disconnection from a Service
To disconnect from a Service you simply call the services.library
function LoseService() with a pointer to the Entity returned by
FindService().
Example:
...
LoseService(svc_entity);
...
Writing a new Service
Before you write a service, you should have a good grasp on writing
Amiga shared libraries. An example shared library can be found in the
Amiga Libraries RKM.
Each Service must implement at least two LVO's that are used by the
Envoy Services Manager and it's configuration tool. These two LVO's
are StartService() and GetServiceAttrs(). StartService() is called by
Services Manager when there is a new request for a service from a client.
The second call, GetServiceAttrs() is used by the Services Manager
configuration tool to determine the name of your service (not to be
confused with your Service's filename).
When the Services Manager calls your StartService() function, you must
take whatever steps are required to start providing your service to the
requesting client. You will be passed information such as the name of
the user and his password. You will also be passed a pointer to string
that you are to fill in with the name of the Entity that the client should
connect to.
Depending on how you are designing your service, you may or may not need
to start a new task for each client that connects to you. You will need
at least one task, however. There currently is no way to have a task-less
service.
When your StartService() function returns, the Services Manager will
reply to the client's request for service with the name of the Entity
it should connect to or will return an error code if you could not start
the service for some reason.
The best way to see how all of this works is to examine the source code
for the print spooler service and it's client. These two pieces of code
detail some of the finer points with writing a service that haven't been
covered in this section.
Installing a Service
All you have to do to make the Services Manager start accepting
requests for your service is to run the Services Manage configuration
tool and add your service.
NIPC Network Realms
Nipc.library is designed to work well in both a single physical network and in
internets. In a situation where there is only one physical networks with a
small number of machines, NIPC will work without setting up a Realm. However,
when there are many machines on a single network, or when there are many
different physical networks, it is desirable to logically divide the entire
network into Realms. An Realm is a logical grouping of hosts that may exists
on a single network or separate physical networks. Because of this, Realms
are independent of network topology. A Realm name can always be optionally
provided before a host name, by preceding the hostname with the Realm name and
and a colon character. For instance, "siberia:scratchy" references the
Amiga named 'scratchy' in the Realm "siberia". If a reference is made to a
host without a Realm name, the Realm that the referencer is in is defaulted
to. If you reference "scratchy", and are in the Realm "siberia" yourself,
NIPC will assume you mean "siberia:scratchy". However, if you're in a
different Realm -- say "Software Engineering", -- and wish to reference
machine "scratchy", you must specify "siberia:scratchy" -- as providing only
"scratchy" will resolve to "Software Engineering:scratchy", which at best
will fail, and at worst will resolve a different machine (another one named
"scratchy") than you intended.
Each Realm must have one host that is acting as a "Realm Server". This host
is responsible for propagating all Realm queries to all of the physical
networks within a realm. Because each host in a realm is configured to know
what Realm it is in and its Realm Server's network address is, a Realm Server
does not need to be physically connected to each network in the realm.
Network queries are initiated by calling the nipc.library function
NIPCInquiryA(). This function allows applications to send many different
types of queries. These range from just determining the names of all machines
in a realm, to doing complex queries that can find all machines with exported
filesystems, 68040's, and eight megabytes of ram. For more information, please
read the autodoc for NIPCInquiryA().
If a query sent by a host is for that hosts local network, the query packet is
broadcasted to every machine on that network. Each machine on that network
will respond to the packet if necessary.
If a query is for a specific Realm, the query is sent to the querying host's
Realm Server. The Realm Server then consults its Realm database to see if it
knows anything about the Realm specified in the query. If the Server
determines that the Realm is one of those that it controls, it sends broadcasts
to all of the physical networks that are in the specified realm. Otherwise,
if the Realm specified in the query is controlled by another Realm Server,
the query packet is forwarded to that machine for further processing.
An NIPC Realm is configured by starting the NIPC configuration editor. On the
Realms panel, there are two listview gadgets. The one on the left is for
setting up realms that the Realm Server is in control of. The listview on the
right is for telling the Realm Server about other Realm Servers. Each physical
network in a Realm must have a separate entry in the lefthand listview gadget.
Envoy Network Filesystems
The initial Envoy network filesystem is broken into two halves -- a client,
to access files on remote machines; and a server, to allow remote machines to
access local files. The client and server portions of the filesystem may be
run separately or together, allowing for true peer-to-peer filesystem access.
Both the client and server include security -- a server will not allow a remote
client to create a remote mount unless the username and password pair passed
from the client is authenticated.
Client
The client portion of the filesystem is implemented as a standard AmigaDOS
filesystem, and will be designed to translate DOS packets into Transactions.
Each remote filesystem to be accessed will be a volume on the client
filesystem. Each mount specifies the machine on which to access files, as
well as the directory path to mount on that machine. Each mounted volume
will create a Workbench icon -- allowing simple Amiga point-and-click access
to remote files and directories. The user will not see any difference
between a network-mounted filesystem and, say, a hard disk (other than access
speed, depending on the CPU and network hardware being used). Each remote
mount can automatically be created on system bootup - with no action required
of the user other than initial configuration.
Server
The server portion of the filesystem will translate Transactions initiated by
a remote client into actions taken on a local filesystem. When a client attempts
to mount a filesystem, a client-provided username and password pair must be
authenticated to allow access. When any individual file or directory is
accessed, that user's user-id and any group-ids will be checked against bits
in the multi-user filesystem to determine what access, if any, will be allowed
to the specific file or directory. The fileserver will be able to successfully
recover from most reboots by automatically re-establishing any mounts, locks,
open files, etc.
